This section describes how variables may be used when customizing an update map expression. If you are new to update maps, it is recommended that you first read Understanding Update Maps.
Variable Types and Scoping Rules
Variables may be defined by a for-each block or by an update block (as an output variable). An output variable may be used in an expression if the expression is contained within an update block that depends on the update block that defines the variable. A for each block variable may be used by an expression if the expression is immediately inside the for-each block that defines the variable. However, if the defining for-each block contains any other for each blocks which also contain the expression, the variable may not be used in the expression.
Example: an update map for a customer-orders data service
The image to the left shows an update map for a logical data service about customers and orders (see Understanding Update Maps for more info). Notice that the update block for customers is selected and the name of its output variable $CUSTOMER_key is shown at the bottom of the screen (the output variable is also referred to as the key variable). In this case, $CUSTOMER_key can be referenced anywhere from within the update block for orders (e.g. in a mapping expression or in the condition for the update block).
Also notice that we have two for-each blocks that define the variables $customer and $order. Within the update block for customers, only the $customer variable is visible and within the update block for orders only the $order variable is visible (with one exception which will be discussed next).
These restrictions are in place to prevent unintuitive or complicated behavior by the update map at runtime. If these rules are too restrictive for your application, you may want to consider using XQSE. However, there is one exception to the for each block variable usage rule. If the variable is used as part of a path expression that references a key value, then usage is valid as long as the expression is within the defining block. It is important to note that updates will be effectively disabled for such "outside" mappings (creates and deletes will still work).
Example: an outside mapping to a key value
In the image on the left, the CUSTOMER_ID element in the update block for orders is selected and its mapping expression (fn-bea:value($customer/CID)) is shown at the bottom of the screen. Normally, the variable $customer could not be used within the orders update block since it is not directly contained within the corresponding for-each block. However, since it is being used to reference CID it is allowed because CID is equivalent to the key value of the customer data service. Updates for this outside mapping will be disabled. That is, if customer/CID is modified in the input to the update map procedure, the CUSTOMER_ID element in the orders update block will not have the modified value.
Updating Foreign Key Values
The function fn-bea:coalesce takes 1 or more arguments and simply returns the first argument that is not empty. The function fn-bea:coalesce-equal works the same way except that it additionally checks that all non empty arguments are equal. If it finds that any two non empty arguments are not equal, it will throw an exception at runtime. The automatically generated update map may use fn-bea:coalesce-equal for the mapping expression for foreign key values if it can be inferred from the target data service that the values should always be equal.
If an argument to fn-bea:coalsece-equal contains an a path expression that falls under the exception to the for each block variable rule mentioned above, then updates will be disabled for the entire expression containing fn-bea:coalsece-equal. If your automatically generated update map is in this situation and you wish to be able to update the foreign key value, you can simply remove the argument that contains the offending mapping. (See the example that follows)
Example: coalesce-equal
In the first image on the left, the CUSTOMER_ID element in the update block for orders is selected and its mapping expression (fn-bea:coalesce-equal(...)) is shown at the bottom of the screen. When the update map is used to create a customer with orders, the value for CID may not be known as it may be auto generated by an underlying relational database. This means that $customer/CID and $order/OCID may be empty. In this case the generated key value will be returned and the orders will get the value for CUSTOMER_ID via fn-bea:value($CUSTOMER_key/CUSTOMER_ID). If the update map is used to update or delete customers and orders, $CUSTOMER_key/CUSTOMER_ID will be empty but $customer/CID and $order/OCID should not be.
This mapping contains an outside reference to the variable $customer so updates will be disabled for customer/order/OCID in the input to the update map procedure. To enable updates to OCID, we can remove the outside mapping. The second image on the left shows what the update map looks like after this modification.
Document generated by Confluence on Apr 28, 2008 15:57
